Kiro CLI

1. Introduction to Kiro CLI

Kiro CLI is a powerful command-line tool that brings AI-powered development directly to your terminal. Built on advanced AI models, it understands your codebase, writes and reviews code, automates workflows, and helps you ship faster without leaving the command line.

Whether you are debugging a production server, working in an SSH session, or simply prefer the terminal, Kiro CLI keeps you in your flow state while providing intelligent assistance.

1.1 What Can Kiro CLI Do?

• Write and modify code across your entire codebase with context-aware suggestions
• Code intelligence with tree-sitter and LSP for symbol search, pattern matching, and navigation
• Custom agents tailored to specific workflows like code review, AWS infrastructure, or debugging
• Skills that bundle tools and knowledge for specialized tasks
• MCP integration to connect external tools via the Model Context Protocol
• Subagents for parallel task delegation and complex multi-step operations
• Hooks for automating workflows at specific lifecycle points
• ACP support to use Kiro inside JetBrains IDEs, Zed, and other editors

1.2 Supported Languages

Kiro CLI supports 18+ programming languages including Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, Scala, Lua, Elixir, Bash, and TSX.

2. Installation & Setup

2.1 Prerequisites

Before installing Kiro CLI, you need an AWS Builder ID. Visit the AWS Builder ID page and select "Sign up with Builder ID" to create one. This is free and takes just a few minutes.

2.2 Installing Kiro CLI

macOS and Linux (recommended):

curl -fsSL https://cli.kiro.dev/install | bash

Linux AppImage (portable, no root required)

# Download the AppImage
wget https://desktop-release.q.us-east-1.amazonaws.com/latest/kiro-cli.appimage

# Make it executable
chmod +x kiro-cli.appimage

# Run directly
./kiro-cli.appimage

Ubuntu / Debian (DEB package)

wget https://desktop-release.q.us-east-1.amazonaws.com/latest/kiro-cli.deb
sudo dpkg -i kiro-cli.deb
sudo apt-get install -f
kiro-cli

Linux ZIP (manual install)

# Download and unzip
unzip kirocli.zip

# Install to ~/.local/bin (default)
./kirocli/install.sh

Uninstalling

# macOS
kiro-cli uninstall

# Ubuntu / Debian
sudo apt-get remove kiro-cli
sudo apt-get purge kiro-cli

2.3 Authentication

After installation, run kiro-cli and it will open your web browser for authentication. Sign in with your AWS Builder ID to complete the setup.

# Start Kiro CLI for the first time
kiro-cli

# It will open your browser for authentication
# Follow the on-screen instructions to sign in

2.4 Proxy Support

Kiro CLI (v1.8.0+) automatically respects standard proxy environment variables, making it compatible with enterprise environments that use proxy servers.

# Set proxy environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

# For authenticated proxies, include credentials in the URL
export HTTPS_PROXY=http://user:password@proxy.company.com:8080

3. Getting Started with Chat

The primary way to interact with Kiro CLI is through its chat interface. When you start kiro-cli without any subcommand, it defaults to chat mode.

3.1 Starting a Chat Session

# Start a chat session (default)
kiro-cli chat

# Or simply
kiro-cli

# Start with a specific agent
kiro-cli chat --agent my-agent

# Resume the last conversation in this directory
kiro-cli chat --resume

# Interactive session picker to choose which conversation to resume
kiro-cli chat --resume-picker

Multi-line Input

For longer or more complex prompts, use the built-in editor support:

# Open your default editor (vi) to compose a message
/editor

# Or press Ctrl+J to open the editor inline

# Reply to the last assistant message with quoted context
/reply

Saving and Loading Conversations

# Save current conversation
/chat save ~/my-sessions/review-session -f

# Load a previous conversation (replaces current chat)
/chat load ~/my-sessions/review-session

3.2 Model Selection

3.3 Inline File References

Starting with v1.26.0, you can reference files directly in your messages using the @path syntax.

# Reference a specific file
> Look at @src/utils/auth.ts and find the login function

# Reference multiple files
> Compare @package.json with @package-lock.json

4. Slash Commands Reference

Slash commands are special commands you type during a chat session that start with a forward slash (/). They provide quick access to various Kiro CLI features.

5. Built-in Tools

Kiro CLI comes with a set of built-in tools that the AI agent uses to interact with your system.

6. Code Intelligence

One of Kiro CLI's most powerful features is its two-tier code intelligence system. It combines tree-sitter (built-in) for immediate code understanding with optional LSP integration for enhanced precision.

6.1 Tree-sitter (Built-in)

Tree-sitter provides out-of-the-box code intelligence for 18 languages with no setup required. It supports fuzzy symbol matching, document symbols, and definition lookup. With incremental loading, it can efficiently handle codebases with millions of tokens.

Key Operations:

6.2 LSP Integration (Optional)

For enhanced precision, enable Language Server Protocol integration:

# Initialize LSP for your workspace
/code init

# This will:
# 1. Detect languages from project markers (package.json, Cargo.toml, etc.)
# 2. Start appropriate language servers
# 3. Enable enhanced features

LSP adds: find references, go to definition, hover documentation, rename refactoring, and diagnostics. Pre-configured for TypeScript, Rust, Python, Go, Java, Ruby, and C/C++.

7. Custom Agents

Custom agents let you define specialized AI configurations for specific workflows, reducing interruptions by pre-approving trusted tools and automatically including relevant context.

7.1 Creating a Custom Agent

# Interactive agent creation
/agent generate

# Or via CLI command
kiro-cli agent create my-agent

# List all available agents
kiro-cli agent list

# Switch to a different agent
/agent swap my-agent

7.2 Agent Configuration File

Example code review agent:

{
  "name": "code-reviewer",
  "description": "Code review agent focused on quality and security",
  "tools": ["fs_read", "code", "grep", "glob", "@git"],
  "allowedTools": ["fs_read", "code", "grep", "glob"],
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git"]
    }
  },
  "shellSettings": {
    "allowedCommands": ["git diff.*", "git log.*", "git show.*"],
    "deniedCommands": ["rm -rf.*", "git push.*"]
  },
  "hooks": {
    "userPromptSubmit": [
      {
        "command": "echo 'Focus: code quality, security, best practices'",
        "timeout_ms": 5000
      }
    ]
  }
}

7.3 Agent Scopes

7.4 Key Configuration Options

7.5 Example Agents

Minimal Agent — Start Here

Save this as .kiro/agents/helper.json in your project root. It gives you a basic agent with file access and shell commands pre-approved so you can work without permission prompts:

{
  "name": "helper",
  "description": "General-purpose dev assistant with file and shell access",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "grep",
    "glob",
    "code"
  ],
  "allowedTools": [
    "fs_read",
    "fs_write",
    "grep",
    "glob",
    "code"
  ],
  "resources": [
    "file://.kiro/steering/**/*.md"
  ]
}

More Agent Examples

• AWS Infrastructure Agent — Pre-approved AWS tools with relevant documentation loaded via resources
• Code Review Agent — Read-only file access with deniedCommands blocking any write operations
• Mobile App Backend Agent — Docker and database MCP servers with toolAliases to resolve naming conflicts

8. Skills

Skills are reusable bundles of tools, knowledge, and workflows for specialized tasks. They activate dynamically when you invoke them via slash commands, giving the agent procedural knowledge for specific jobs.

8.1 How Skills Work

Type / in the chat input to see available skills as slash commands. Selecting a slash command loads the full skill instructions into the agent's context. Skills can include:

• Procedural knowledge — step-by-step instructions for complex workflows
• Tool configurations — MCP servers and tool settings bundled together
• Best practices — coding standards, patterns, and conventions for specific frameworks
• Templates — reusable prompts for common tasks like code review, deployment, or debugging

8.2 Skill Scopes

8.3 Discovering Skills on skills.sh

skills.sh is an open community directory with 69,000+ reusable skills for AI agents, including Kiro CLI. You can browse, search, and install skills with a single command.

Installing a Skill

# Install a skill from the community directory
npx skills-add owner/skill-name

# Examples:
npx skills-add anthropics/find-skills
npx skills-add vercel/react-best-practices
npx skills-add frontend-design

Installed skills appear as slash commands in your chat session. Type / to see all available skills.

Popular Skills Worth Installing

8.4 Creating Custom Skills

Skills are directories containing instruction files and optional configuration. A minimal skill is just a markdown file with instructions:

# Create a workspace-level skill
mkdir -p .kiro/skills/deploy

# The skill instruction file
# .kiro/skills/deploy/instructions.md
# ─────────────────────────────────────
# Deployment Procedure
#
# 1. Run the test suite: npm test
# 2. Build the production bundle: npm run build
# 3. Deploy to staging: ./scripts/deploy.sh staging
# 4. Run smoke tests against staging
# 5. If smoke tests pass, deploy to production: ./scripts/deploy.sh production
# 6. Verify health checks at /api/health

Once created, invoke it with /deploy in your chat session.

9. MCP (Model Context Protocol)

MCP is an open standard that allows Kiro CLI to communicate with external servers for specialized tools and information — like a plugin system.

9.1 Configuration Files

9.2 Local Server Configuration

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git"],
      "env": {
        "GIT_CONFIG_GLOBAL": "/dev/null"
      }
    },
    "web-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-bravesearch"],
      "env": {
        "BRAVE_API_KEY": "env_variable_ref"
      }
    }
  }
}

9.3 Remote Server Configuration

{
  "mcpServers": {
    "api-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer token_ref",
        "X-Custom-Header": "value"
      }
    }
  }
}

9.4 Managing MCP Servers

# Add a new MCP server with full options
kiro-cli mcp add \
  --name "awslabs.aws-documentation-mcp-server" \
  --scope global \
  --command "uvx" \
  --args "awslabs.aws-documentation-mcp-server@latest" \
  --env "FASTMCP_LOG_LEVEL=ERROR"

# Add to workspace scope
kiro-cli mcp add --name myserver --scope workspace

# Add to specific agent
kiro-cli mcp add --name myserver --agent myagent

# View active servers in chat
/mcp

MCP Tool Validation Requirements

• Tool name (including server prefix) must be ≤ 64 characters
• Tool name must match: ^[a-zA-Z][a-zA-Z0-9_]*$
• Tool description cannot be empty and should be ≤ 10,000 characters

9.5 Enterprise Governance

For enterprise teams, Kiro CLI supports MCP Registry mode. Administrators can create a JSON allowlist of approved servers, serve it over HTTPS, and configure it. When registry mode is active, users cannot add custom servers.

10. Hooks

Hooks let you execute custom commands at specific points during the agent lifecycle.

10.1 Hook Trigger Points

Exit Code Behavior

Hook Event Data (JSON via STDIN)

Hooks receive a JSON payload via STDIN containing:

• hook_event_name - The trigger point identifier
• cwd - Current working directory
• tool_name - Tool being executed (PreToolUse / PostToolUse only)
• tool_input - Tool input parameters (PreToolUse / PostToolUse only)
• tool_response - Tool execution result (PostToolUse only)

Tool Matching with matcher

Use the matcher field to target specific tools:

10.2 Hook Configuration Example

"hooks": {
  "agentSpawn": [
    {
      "command": "cat .kiro/project-context.md",
      "timeout_ms": 5000
    }
  ],
  "preToolUse": {
    "fs_write": [
      {
        "command": "echo 'Validating file write...'",
        "timeout_ms": 10000,
        "cache_ttl_seconds": 300
      }
    ]
  }
}

11. Subagents & Task Delegation

Subagents are specialized agents that can autonomously execute complex tasks with their own context.

11.1 How Subagents Work

When you assign a task to a subagent, Kiro delegates the work to a separate agent context. This prevents context window bloat and allows parallel execution.

11.2 Key Capabilities

Subagents support autonomous execution with live progress tracking, access to core tools, parallel execution, and results aggregation.

11.3 Controlling Subagent Access

"availableAgents": ["reviewer", "tester", "deployer", "researcher"],
"trustedAgents": ["reviewer", "tester"]

// reviewer and tester run without permission prompts
// deployer and researcher require approval

11.4 The Delegate Tool

For long-running tasks, use the delegate tool for background agents running asynchronously.

12. Planning Mode

Kiro CLI includes a built-in Plan Agent for breaking down complex tasks into structured implementation plans. The Plan Agent operates in read-only mode.

12.1 When to Use Planning Mode

Use for large feature implementations, refactoring projects, architecture decisions, or any complex task.

12.2 How It Works

The Plan Agent can read files, search symbols, and explore your codebase structure to produce structured plans.

13. Experimental Features

Use the /experiment command to toggle cutting-edge features.

13.1 Knowledge Management

Persistent context storage and retrieval with semantic search capabilities.

kiro-cli settings chat.enableKnowledge true
kiro-cli settings knowledge.maxFiles 10000

13.2 TODO Lists

kiro-cli settings chat.enableTodoList true
/todo resume

13.3 Thinking Tool

Shows the AI's step-by-step reasoning process.

kiro-cli settings chat.enableThinking true

13.4 Checkpoints

Session-scoped checkpoints for tracking file changes.

kiro-cli settings chat.enableCheckpoint true

13.5 Tangent Mode

Create conversation checkpoints to explore side topics without disrupting main flow.

kiro-cli settings chat.enableTangentMode true

13.6 Delegate (Background Agents)

Launch and manage asynchronous task processes in parallel.

14. Agent Client Protocol (ACP)

Kiro CLI implements ACP, an open standard for AI agents to work with any compatible editor.

14.1 What is ACP?

ACP provides standardized agent-editor communication via JSON-RPC over stdin/stdout, similar to LSP.

14.2 Starting ACP Mode

# Start Kiro as an ACP agent
kiro-cli acp

# Start with a specific agent configuration
kiro-cli acp --agent my-agent

14.3 Supported ACP Methods

Kiro supports standard ACP methods plus extensions for slash commands, MCP tools, and session management:

Sessions persist to ~/.kiro/sessions/cli/ as JSON metadata and JSONL event logs, so you can resume from any editor.

14.4 Setting Up in VS Code

Step 1: Install the ACP Client extension from the VS Code Marketplace (by Formula Hendry), or search for "ACP Client" in the Extensions panel.

Step 2: Open your VS Code settings.json (Ctrl+Shift+P → "Preferences: Open User Settings (JSON)") and add:

{
  "acp.agents": {
    "Kiro Agent": {
      "command": "/full/path/to/kiro-cli",
      "args": ["acp"],
      "env": {}
    }
  }
}

Step 3: Open the ACP Client panel from the Activity Bar (look for the ACP icon on the left sidebar).

Step 4: Click Kiro Agent to connect, or use the Command Palette (Ctrl+Shift+P) and run ACP: Connect to Agent.

You can now chat with Kiro directly inside VS Code. It has full access to your workspace files and tools.

14.5 Setting Up in JetBrains IDEs (WebStorm, PhpStorm, IntelliJ)

This works identically in WebStorm, PhpStorm, IntelliJ IDEA, and all other JetBrains IDEs.

Step 1: Open the AI Chat tool window (usually on the right sidebar). If you don't see it, go to View → Tool Windows → AI Chat.

Step 2: Click the settings gear icon in the AI Chat panel and select "Add Custom Agent".

Step 3: This opens (or creates) the file ~/.jetbrains/acp.json. Add the following configuration:

{
  "agent_servers": {
    "Kiro Agent": {
      "command": "/full/path/to/kiro-cli",
      "args": ["acp"]
    }
  }
}

Step 4: Save the file. Back in the AI Chat panel, click the model/agent dropdown and select Kiro Agent.

Kiro now appears as an option in the AI Chat mode selector across all your JetBrains IDEs.

15. Managing Prompts

Kiro CLI supports reusable prompt templates.

15.1 Using Prompts

/prompt list
/prompt my-review-template

15.2 Conversation Persistence

/save my-session-name
/load my-session-name

16. Configuration & Settings

Kiro CLI provides extensive customization through a layered settings system.

16.1 Configuration Scopes

16.2 Managing Settings

kiro-cli settings list
kiro-cli settings list --all
kiro-cli settings telemetry.enabled true
kiro-cli settings chat.enableKnowledge true
kiro-cli settings chat.enableThinking true
kiro-cli settings chat.enableTodoList true
kiro-cli settings chat.enableCheckpoint true

17. CLI Commands Quick Reference

A complete reference of all CLI commands and their common options:

18. Agent Steering

Steering files provide persistent project knowledge through markdown documents, enabling consistent AI-guided code generation without repeating conventions in every conversation. Think of them as always-on context that shapes how Kiro understands and works with your codebase.

18.1 Steering File Scopes

18.2 Foundational Files

Three core steering files establish baseline context for any project:

# Example: .kiro/steering/tech.md
## Tech Stack
- **Runtime**: Node.js 20 LTS
- **Framework**: Next.js 15 with App Router
- **Database**: PostgreSQL via Prisma ORM
- **Testing**: Vitest for unit tests, Playwright for E2E
- **Styling**: Tailwind CSS with shadcn/ui components

## Conventions
- Use server components by default; add "use client" only when needed
- All API routes return JSON with { data, error } envelope
- Environment variables must be validated at startup with zod

18.3 Custom Steering Strategy

Create specialized files addressing specific domains your team cares about:

• api-standards.md - REST conventions, authentication flows, error codes
• testing-standards.md - Unit / integration test patterns, coverage expectations
• code-conventions.md - Naming, organization, architectural decisions
• security-policies.md - Validation, sanitization, secure coding practices
• deployment-workflow.md - Build steps, environment config, CI/CD procedures

18.4 AGENTS.md Support

Kiro supports the AGENTS.md standard for steering directives. Place an AGENTS.md file in ~/.kiro/steering/ or your workspace root and it will be automatically included without explicit configuration.

{
  "resources": ["file://.kiro/steering/**/*.md"]
}

19. Autocomplete & Inline Suggestions

Kiro CLI provides two AI-powered terminal assistance features that work independently: an autocomplete dropdown menu and inline ghost-text suggestions. Both support hundreds of popular CLI tools.

19.1 Autocomplete Dropdown

A graphical menu appears to the right of your cursor as you type, showing available options, subcommands, and arguments. Navigate with arrow keys and press Tab or Enter to select.

Autocomplete is enabled by default after installation. It works with your regular terminal - just start typing any supported command.

Supported Tools

19.2 Inline Suggestions

Gray "ghost text" appears directly on the command line as you type, offering full command completions based on context. Press the right arrow key or Tab to accept, or keep typing to ignore.

# Manage inline suggestions
kiro-cli inline enable              # Activate
kiro-cli inline disable             # Deactivate
kiro-cli inline status              # Check current state
kiro-cli inline set-customization [ARN]   # Set custom model
kiro-cli inline show-customizations       # List customizations

19.3 Configuration & Themes

# Enable or disable autocomplete
kiro-cli settings autocomplete.disable false   # Enable (default)
kiro-cli settings autocomplete.disable true    # Disable

# Theme management
kiro-cli theme dark       # Dark theme
kiro-cli theme light      # Light theme
kiro-cli theme system     # Follow system preference
kiro-cli theme            # View current theme
kiro-cli theme --list     # List all available themes

20. Tips & Best Practices

20.1 Getting the Most from Kiro CLI

• Start with the Help Agent - Type /help to get guidance on any feature
• Set up steering files early - Create .kiro/steering/tech.md and structure.md so Kiro understands your project conventions from the first conversation
• Run /code init for LSP - Enable Language Server Protocol integration for precise go-to-definition, references, and diagnostics
• Use custom agents for repetitive workflows - Build agents for code review, deployment, debugging, and infrastructure tasks to avoid reconfiguring permissions each time
• Use subagents for parallel tasks - Delegate independent tasks to subagents to avoid context window bloat and speed up complex operations
• Leverage --resume for continuity - Use kiro-cli chat --resume to pick up where you left off in a directory
• Use /editor for complex prompts - Press Ctrl+J or type /editor to compose detailed multi-line instructions in your favorite editor
• Pre-approve trusted tools - Use allowedTools in agent configs to eliminate permission prompts for tools you trust
• Use hooks for automation - Set up agentSpawn hooks to inject project context automatically and stop hooks to run formatters/linters after code generation
• Monitor token usage - Use /tools to see estimated token counts per tool and per MCP server (v1.26.0+)

20.2 Security Best Practices

• Use IAM roles with least-privilege access - Only grant the permissions Kiro needs for the task at hand
• Enable MFA for sensitive operations and production environment access
• Always review generated code before deploying - AI-generated code should go through the same review process as human-written code
• Restrict shell commands - Use shellSettings.allowedCommands and deniedCommands with regex patterns to prevent dangerous operations
• Never hardcode secrets - Use environment variable references in MCP configs and never commit credentials to version control
• Use preToolUse hooks for security validation - block dangerous tool calls with exit code 2
• Audit MCP servers - Only use trusted MCP servers. For enterprise teams, use MCP Registry mode to maintain an allowlist of approved servers
• Limit subagent access - Use availableAgents and trustedAgents to control which agents can be spawned and which require approval

20.3 Troubleshooting

Kiro CLI includes built-in diagnostics to help resolve common issues:

# Run the diagnostic tool to identify and resolve issues
kiro-cli doctor

# Report a bug with system info automatically attached
kiro-cli issue

20.4 Useful Resources

• Kiro CLI Official Documentation
• Code Intelligence
• Custom Agents
• MCP Configuration
• Hooks
• ACP
• Changelog